001 /*
002 * Copyright 2005 Stephen J. McConnell
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
013 * implied.
014 *
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019 package net.dpml.library;
020
021 import java.io.File;
022
023 import net.dpml.library.info.Scope;
024 import net.dpml.library.info.ResourceDirective.Classifier;
025
026 import net.dpml.transit.Artifact;
027
028 import net.dpml.lang.Category;
029 import net.dpml.lang.Version;
030
031 import net.dpml.util.Resolver;
032
033 /**
034 * The Resource interface describes infomation about a published resource.
035 *
036 * @author <a href="http://www.dpml.net">Digital Product Meta Library</a>
037 * @version 1.1.0
038 */
039 public interface Resource extends Dictionary, Resolver
040 {
041 /**
042 * System property name used to declare the decimal versioning enabled flag.
043 */
044 public static final String DECIMAL_VERSIONING_KEY = "project.decimal.versioning.enabled";
045
046 /**
047 * Return the singleton library.
048 * @return the library
049 */
050 Library getLibrary();
051
052 /**
053 * Return the name of the resource.
054 * @return the resource name
055 */
056 String getName();
057
058 /**
059 * Return the resource version.
060 * @return the version
061 */
062 String getVersion();
063
064 /**
065 * Return the statutory resource version.
066 * @return the version
067 */
068 String getStatutoryVersion();
069
070 /**
071 * Return the decimal version.
072 * @return the version
073 */
074 Version getDecimalVersion();
075
076 /**
077 * Return the fully qualified path to the resource.
078 * @return the path
079 */
080 String getResourcePath();
081
082 /**
083 * Return the basedir for this resource.
084 * @return the base directory (possibly null)
085 */
086 File getBaseDir();
087
088 /**
089 * Return the info block.
090 * @return the info block
091 */
092 Info getInfo();
093
094 /**
095 * Return the resource classifier.
096 * @return the classifier (LOCAL, EXTERNAL or ANONYMOUS)
097 */
098 Classifier getClassifier();
099
100 /**
101 * Return the expanded array of types associated with the resource.
102 * The returned array is a function of the types declared by a resource
103 * expanded relative to any types implied by processor dependencies.
104 * @return the type array
105 */
106 Type[] getTypes();
107
108 /**
109 * Test if this resource is associated with a type of the supplied name.
110 * @param type the type id
111 * @return TRUE if this resource produces an artifact of the supplied type
112 */
113 boolean isa( String type );
114
115 /**
116 * Return a resource type relative to a supplied type id.
117 * @param id the type name to retrieve
118 * @return the type instance
119 */
120 Type getType( String id );
121
122 /**
123 * Construct an artifact for the supplied type.
124 * @param type the resource type id
125 * @return the artifact
126 */
127 Artifact getArtifact( String type );
128
129 /**
130 * Construct an unversion link artifact for the supplied type.
131 * @param type the resource type id
132 * @return the link artifact
133 */
134 Artifact getLinkArtifact( String type );
135
136 /**
137 * Return the enclosing parent module.
138 * @return the enclosing module of null if this a top-level module.
139 */
140 Module getParent();
141
142 /**
143 * Return an array of resource that are providers to this resource.
144 * @param scope the operational scope
145 * @param expand if true include transitive dependencies
146 * @param sort if true the array will sorted relative to dependencies
147 * @return the resource providers
148 */
149 Resource[] getProviders( Scope scope, boolean expand, boolean sort );
150
151 /**
152 * Return an array of resource that are providers to this resource. If
153 * the supplied scope is BUILD the returned resource array is equivalent
154 * <src>getProviders( Scope.BUILD, .. )</src>. If the scope is RUNTIME
155 * the returned resource array includes BUILD and RUNTIME resources. If
156 * the scope is TEST the returned array includes BUILD, RUNTIME and TEST
157 * resources.
158 * @param scope the scope of aggregation to be applied to the selection
159 * @param expand if TRUE include transitive dependencies
160 * @param sort if true the array will sorted relative to dependencies
161 * @return the resource providers
162 */
163 Resource[] getAggregatedProviders( Scope scope, boolean expand, boolean sort );
164
165 /**
166 * Return a sorted and filtered array of providers. Resources not declaring
167 * the "jar" type as a produced type are excluded from selection. The
168 * resource array will include transitive dependencies. The method is
169 * suitable for the construction of build and test phase classloaders.
170 *
171 * @param scope the aggregation scope
172 * @return the scoped resource chain
173 */
174 Resource[] getClasspathProviders( Scope scope );
175
176 /**
177 * Return an array of runtime providers filtered relative to a supplied
178 * classloading category. Resources not declaring the "jar" type as a
179 * produced type are excluded from selection. The resource array returned
180 * from this operation is a sorted transitive sequence excluding all
181 * resource references by any category higher than the supplied category.
182 * This method is typically used to construct information suitable for
183 * the gerneration of plugin metadata.
184 *
185 * @param category the classloader category
186 * @return the category scoped resource chain
187 */
188 Resource[] getClasspathProviders( Category category );
189
190 /**
191 * Return an array of resources that are consumers of this resource.
192 * @param expand if true the returned array includes consumers associated
193 * through transitive dependency relationships, otherwise the array is
194 * limited to direct consumers
195 * @param sort if true the array is sorted relative to depenency relationships
196 * @return the array of consumer projects
197 */
198 Resource[] getConsumers( boolean expand, boolean sort );
199
200 /**
201 * Return an array of filters associated with the resource.
202 * @return the array of filters
203 */
204 Filter[] getFilters();
205
206 /**
207 * Return a filename using the layout strategy employed by the cache.
208 * @param id the artifact type
209 * @return the filename
210 */
211 String getLayoutPath( String id );
212
213 /**
214 * Return the array of production data.
215 * @return the associated production data
216 */
217 Data[] getData();
218 }